package com.streambolics.std;

/**
 * An object capable of building a simple text to be shown to a user.
 * 
 * @author Sauron
 * 
 */

public interface TextBuilder extends AnchorBuilder
{
    /**
     * Adds a paragraph to the text being built.
     * 
     * The paragraph consists of all concatenated arguments. A single paragraph
     * is created, even if multiple arguments are given.
     * 
     * addParagraph is semantically equivalent to calling openParagraph(),
     * addText(), closeParagraph().
     * 
     * @param aTexts
     *            The texts to be concatenated to form the paragraph.
     */

    void addParagraph (String... aTexts);

    /**
     * Adds raw strings to the text being built.
     * 
     * The strings are concatenated as is, without intervening white space.
     * 
     * @param aTexts
     *            The texts to be added.
     */

    void addText (String... aTexts);

    /**
     * Closes the paragraph opened by openParagraph().
     */

    void closeParagraph ();

    /**
     * Opens a paragraph so that text can be appended to it.
     */

    void openParagraph ();
}
